home *** CD-ROM | disk | FTP | other *** search
/ QuickTime 2.0 Developer Kit / QuickTime 2.0 Developer Kit.iso / mac / MAC / Programming Stuff / Interfaces / CIncludes / SoundComponents.h < prev    next >
Encoding:
C/C++ Source or Header  |  1994-11-11  |  15.5 KB  |  422 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        SoundComponents.h
  3.  
  4.      Copyright:    © 1984-1994 by Apple Computer, Inc.
  5.                  All rights reserved.
  6.  
  7.      Version:    Universal Interfaces 2.0a3  ETO #16, MPW prerelease.  Friday, November 11, 1994. 
  8.  
  9.      Bugs?:        If you find a problem with this file, send the file and version
  10.                  information (from above) and the problem description to:
  11.  
  12.                      Internet:    apple.bugs@applelink.apple.com
  13.                      AppleLink:    APPLE.BUGS
  14.  
  15. */
  16.  
  17. #ifndef __SOUNDCOMPONENTS__
  18. #define __SOUNDCOMPONENTS__
  19.  
  20. #ifndef rez
  21.  
  22. #ifndef __TYPES__
  23. #include <Types.h>
  24. #endif
  25. /*    #include <ConditionalMacros.h>                                */
  26.  
  27. #ifndef __COMPONENTS__
  28. #include <Components.h>
  29. #endif
  30. /*    #include <MixedMode.h>                                        */
  31.  
  32. #ifndef __SOUND__
  33. #include <Sound.h>
  34. #endif
  35.  
  36. #ifdef __cplusplus
  37. extern "C" {
  38. #endif
  39.  
  40. #if GENERATINGPOWERPC
  41. #pragma options align=mac68k
  42. #endif
  43.  
  44. #ifdef __CFM68K__
  45. #pragma lib_export on
  46. #endif
  47.  
  48. #endif /* rez */
  49. /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
  50. /* constants*/
  51. /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
  52.  
  53.  
  54. /*sound component types and subtypes*/
  55. #define kNoSoundComponentType            '****'
  56.  
  57.  
  58. #define kSoundHardwareType                'sdev'        /*component type for sound devices*/
  59. #define kSoundComponentType                'sift'
  60. #define     kRate8SubType                'ratb'        /*8-bit rate converter*/
  61. #define     kRate16SubType                'ratw'        /*16-bit rate converter*/
  62. #define kConverterSubType                'conv'        /*sample format converter*/
  63. #define kSndSourceSubType                'sour'        /*generic source component*/
  64.  
  65.  
  66. #define kMixerType                        'mixr'
  67. #define     kMixer8SubType                'mixb'        /*8-bit mixer*/
  68. #define     kMixer16SubType                'mixw'        /*16-bit mixer*/
  69.  
  70.  
  71. #define kSoundOutputDeviceType            'sdev'        /*sound output component*/
  72. #define        kClassicSubType                'clas'        /*classic hardware, i.e. Mac Plus*/
  73. #define     kASCSubType                    'asc '        /*Apple Sound Chip device*/
  74. #define     kDSPSubType                    'dsp '        /*DSP device*/
  75. #define     kAwacsSubType                'awac'        /*Another of Will's Audio Chips device*/
  76. #define     kSingerSubType                'sing'        /*Singer (via Whitney) based sound*/
  77.  
  78.  
  79. #define kSoundCompressor                'scom'
  80. #define kSoundDecompressor                'sdec'
  81. #define     kMace3SubType                'MAC3'        /*MACE 3:1*/
  82. #define     kMace6SubType                'MAC6'        /*MACE 6:1*/
  83. #define     kCDXA4SubType                'cdx4'        /*CD/XA 4:1*/
  84. #define     kCDXA2SubType                'cdx2'        /*CD/XA 2:1*/
  85. #define     kIMA4SubType                'ima4'        /*IMA 4:1*/
  86.  
  87.  
  88. /*Audio components and sub-types*/
  89. #define kAudioComponentType                'adio'
  90. #define        kAwacsPhoneSubType            'hphn'
  91. #define        kAudioVisionSpeakerSubType    'telc'
  92. #define        kAudioVisionHeadphoneSubType 'telh'
  93.  
  94.  
  95. /*features flags*/
  96. #define k8BitRawIn                    (1 << 0)    /*data description*/
  97. #define k8BitTwosIn                    (1 << 1)
  98. #define k16BitIn                    (1 << 2)
  99. #define kStereoIn                    (1 << 3)
  100. #define k8BitRawOut                    (1 << 8)
  101. #define k8BitTwosOut                (1 << 9)
  102. #define k16BitOut                    (1 << 10)
  103. #define kStereoOut                    (1 << 11)
  104.  
  105.  
  106. #define kReverse                    (1 << 16)    /*function description*/
  107. #define kRateConvert                (1 << 17)
  108. #define kCreateSoundSource            (1 << 18)
  109.  
  110.  
  111. #define kHighQuality                (1 << 22)    /*performance description*/
  112. #define kRealTime                    (1 << 23)
  113.  
  114.  
  115. #ifndef rez
  116.  
  117. enum {
  118. /*sound component set/get info selectors*/
  119.     siVolume                    = 'volu',
  120.     siHardwareVolume            = 'hvol',
  121.     siSpeakerVolume                = 'svol',
  122.     siHeadphoneVolume            = 'pvol',
  123.     siHardwareVolumeSteps        = 'hstp',
  124.     siHeadphoneVolumeSteps        = 'hdst',
  125.     siHardwareMute                = 'hmut',
  126.     siSpeakerMute                = 'smut',
  127.     siHeadphoneMute                = 'pmut',
  128.     siRateMultiplier            = 'rmul',
  129.     siQuality                    = 'qual',
  130. /*format types*/
  131.     kOffsetBinary                = 'raw ',
  132.     kTwosComplement                = 'twos',
  133.     kMACE3Compression            = 'MAC3',
  134.     kMACE6Compression            = 'MAC6'
  135. };
  136.  
  137. /*quality flags*/
  138. enum {
  139. /*use interpolation in rate conversion*/
  140.     kBestQuality                = (1 << 0)
  141. };
  142.  
  143. enum {
  144. /*useful bit masks*/
  145.     kInputMask                    = 0x000000FF,                    /*masks off input bits*/
  146.     kOutputMask                    = 0x0000FF00,                    /*masks off output bits*/
  147.     kOutputShift                = 8,                            /*amount output bits are shifted*/
  148.     kActionMask                    = 0x00FF0000,                    /*masks off action bits*/
  149.     kSoundComponentBits            = 0x00FFFFFF
  150. };
  151.  
  152. enum {
  153. /*SoundComponentPlaySourceBuffer action flags*/
  154.     kSourcePaused                = (1 << 0),
  155.     kPassThrough                = (1 << 16),
  156.     kNoSoundComponentChain        = (1 << 17),
  157. /*flags for OpenMixerSoundComponent*/
  158.     kNoMixing                    = (1 << 0),                        /*don't mix source*/
  159.     kNoSampleRateConversion        = (1 << 1),                        /*don't convert sample rate (i.e. 11 kHz -> 22 kHz)*/
  160.     kNoSampleSizeConversion        = (1 << 2),                        /*don't convert sample size (i.e. 16 -> 8)*/
  161.     kNoSampleFormatConversion    = (1 << 3),                        /*don't convert sample format (i.e. 'twos' -> 'raw ')*/
  162.     kNoChannelConversion        = (1 << 4),                        /*don't convert stereo/mono*/
  163.     kNoDecompression            = (1 << 5),                        /*don't decompress (i.e. 'MAC3' -> 'raw ')*/
  164.     kNoVolumeConversion            = (1 << 6),                        /*don't apply volume*/
  165.     kNoRealtimeProcessing        = (1 << 7)                        /*won't run at interrupt time*/
  166. };
  167.  
  168. /*Audio Component constants*/
  169. enum {
  170. /*Values for whichChannel parameter*/
  171.     audioAllChannels            = 0,                            /*All channels (usually interpreted as both left and right)*/
  172.     audioLeftChannel            = 1,                            /*Left channel*/
  173.     audioRightChannel            = 2,                            /*Right channel*/
  174. /*Values for mute parameter*/
  175.     audioUnmuted                = 0,                            /*Device is unmuted*/
  176.     audioMuted                    = 1,                            /*Device is muted*/
  177. /*Capabilities flags definitions*/
  178.     audioDoesMono                = (1L << 0),                    /*Device supports mono output*/
  179.     audioDoesStereo                = (1L << 1),                    /*Device supports stereo output*/
  180.     audioDoesIndependentChannels = (1L << 2)                    /*Device supports independent software control of each channel*/
  181. };
  182.  
  183. /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
  184. /* typedefs*/
  185. /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
  186.  
  187.  
  188. /*ShortFixed consists of an 8 bit, 2's complement integer part in the high byte,*/
  189. /*with an 8 bit fractional part in the low byte; its range is -128 to 127.99609375*/
  190. typedef short ShortFixed;
  191.  
  192. typedef struct SoundComponentData SoundComponentData;
  193.  
  194. typedef struct SoundComponentData *SoundComponentDataPtr;
  195.  
  196. struct SoundComponentData {
  197.     long                            flags;
  198.     OSType                            format;
  199.     short                            numChannels;
  200.     short                            sampleSize;
  201.     UnsignedFixed                    sampleRate;
  202.     long                            sampleCount;
  203.     Byte                            *buffer;
  204.     long                            reserved;
  205. };
  206. typedef struct SoundParamBlock SoundParamBlock;
  207.  
  208. typedef SoundParamBlock *SoundParamBlockPtr;
  209.  
  210. typedef pascal Boolean (*SoundParamProcPtr)(SoundParamBlockPtr *pb);
  211.  
  212. #if GENERATINGCFM
  213. typedef UniversalProcPtr SoundParamUPP;
  214. #else
  215. typedef SoundParamProcPtr SoundParamUPP;
  216. #endif
  217.  
  218. struct SoundParamBlock {
  219.     long                            recordSize;                    /*size of this record in bytes*/
  220.     SoundComponentData                desc;                        /*description of sound buffer*/
  221.     UnsignedFixed                    rateMultiplier;                /*rate multiplier to apply to sound*/
  222.     short                            leftVolume;                    /*volumes to apply to sound*/
  223.     short                            rightVolume;
  224.     long                            quality;                    /*quality to apply to sound*/
  225.     ComponentInstance                filter;                        /*filter to apply to sound*/
  226.     SoundParamUPP                    moreRtn;                    /*routine to call to get more data*/
  227.     SoundParamUPP                    completionRtn;                /*routine to call when buffer is complete*/
  228.     long                            refCon;                        /*user refcon*/
  229.     short                            result;                        /*result*/
  230. };
  231. typedef struct privateSoundSource *SoundSource;
  232.  
  233. struct AudioInfo {
  234.     long                            capabilitiesFlags;            /*Describes device capabilities*/
  235.     long                            reserved;                    /*Reserved by Apple*/
  236.     unsigned short                    numVolumeSteps;                /*Number of significant increments between min and max volume*/
  237. };
  238. typedef struct AudioInfo AudioInfo;
  239.  
  240. typedef AudioInfo *AudioInfoPtr;
  241.  
  242. /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
  243. /* functions for sound components*/
  244. /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
  245. /*Sound Component dispatch selectors*/
  246.  
  247. enum {
  248. /*these calls cannot be delegated*/
  249.     kSoundComponentInitOutputDeviceSelect = 1,
  250.     kSoundComponentSetSourceSelect = 2,
  251.     kSoundComponentGetSourceSelect = 3,
  252.     kSoundComponentGetSourceDataSelect = 4,
  253.     kSoundComponentSetOutputSelect = 5,
  254.     kDelegatedSoundComponentSelectors = 0x0100,                    /*first selector that can be delegated up the chain*/
  255. /*these calls can be delegated and have own range*/
  256.     kSoundComponentAddSourceSelect = kDelegatedSoundComponentSelectors + 1,
  257.     kSoundComponentRemoveSourceSelect = kDelegatedSoundComponentSelectors + 2,
  258.     kSoundComponentGetInfoSelect = kDelegatedSoundComponentSelectors + 3,
  259.     kSoundComponentSetInfoSelect = kDelegatedSoundComponentSelectors + 4,
  260.     kSoundComponentStartSourceSelect = kDelegatedSoundComponentSelectors + 5,
  261.     kSoundComponentStopSourceSelect = kDelegatedSoundComponentSelectors + 6,
  262.     kSoundComponentPauseSourceSelect = kDelegatedSoundComponentSelectors + 7,
  263.     kSoundComponentPlaySourceBufferSelect = kDelegatedSoundComponentSelectors + 8
  264. };
  265.  
  266. /*Audio Component selectors*/
  267. enum {
  268.     kAudioGetVolumeSelect        = 0,
  269.     kAudioSetVolumeSelect        = 1,
  270.     kAudioGetMuteSelect            = 2,
  271.     kAudioSetMuteSelect            = 3,
  272.     kAudioSetToDefaultsSelect    = 4,
  273.     kAudioGetInfoSelect            = 5,
  274.     kAudioGetBassSelect            = 6,
  275.     kAudioSetBassSelect            = 7,
  276.     kAudioGetTrebleSelect        = 8,
  277.     kAudioSetTrebleSelect        = 9,
  278.     kAudioGetOutputDeviceSelect    = 10,
  279.     kAudioMuteOnEventSelect        = 129
  280. };
  281.  
  282.  
  283.  
  284. /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
  285. /* Sound Manager 3.0 utilities*/
  286. extern pascal OSErr OpenMixerSoundComponent(SoundComponentDataPtr outputDescription, long outputFlags, ComponentInstance *mixerComponent)
  287.  FOURWORDINLINE(0x203C, 0x0614, 0x0018, 0xA800);
  288. extern pascal OSErr CloseMixerSoundComponent(ComponentInstance ci)
  289.  FOURWORDINLINE(0x203C, 0x0218, 0x0018, 0xA800);
  290.  
  291.  
  292. /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
  293. /* basic sound component functions*/
  294. extern pascal ComponentResult SoundComponentInitOutputDevice(ComponentInstance ti, long actions)
  295.  FIVEWORDINLINE(0x2F3C, 4, 1, 0x7000, 0xA82A);
  296. extern pascal ComponentResult SoundComponentSetSource(ComponentInstance ti, SoundSource sourceID, ComponentInstance source)
  297.  FIVEWORDINLINE(0x2F3C, 8, 2, 0x7000, 0xA82A);
  298. extern pascal ComponentResult SoundComponentGetSource(ComponentInstance ti, SoundSource sourceID, ComponentInstance *source)
  299.  FIVEWORDINLINE(0x2F3C, 8, 3, 0x7000, 0xA82A);
  300. extern pascal ComponentResult SoundComponentGetSourceData(ComponentInstance ti, SoundComponentDataPtr *sourceData)
  301.  FIVEWORDINLINE(0x2F3C, 4, 4, 0x7000, 0xA82A);
  302. extern pascal ComponentResult SoundComponentSetOutput(ComponentInstance ti, SoundComponentDataPtr requested, SoundComponentDataPtr *actual)
  303.  FIVEWORDINLINE(0x2F3C, 8, 5, 0x7000, 0xA82A);
  304.  
  305.  
  306. /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
  307. /* junction methods for the mixer, must be called at non-interrupt level*/
  308. extern pascal ComponentResult SoundComponentAddSource(ComponentInstance ti, SoundSource *sourceID)
  309.  FIVEWORDINLINE(0x2F3C, 4, 0x0101, 0x7000, 0xA82A);
  310. extern pascal ComponentResult SoundComponentRemoveSource(ComponentInstance ti, SoundSource sourceID)
  311.  FIVEWORDINLINE(0x2F3C, 4, 0x0102, 0x7000, 0xA82A);
  312.  
  313.  
  314. /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
  315. /* info methods*/
  316. extern pascal ComponentResult SoundComponentGetInfo(ComponentInstance ti, SoundSource sourceID, OSType selector, void *infoPtr)
  317.  FIVEWORDINLINE(0x2F3C, 12, 0x0103, 0x7000, 0xA82A);
  318. extern pascal ComponentResult SoundComponentSetInfo(ComponentInstance ti, SoundSource sourceID, OSType selector, void *infoPtr)
  319.  FIVEWORDINLINE(0x2F3C, 12, 0x0104, 0x7000, 0xA82A);
  320.  
  321.  
  322. /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
  323. /* control methods*/
  324. extern pascal ComponentResult SoundComponentStartSource(ComponentInstance ti, short count, SoundSource *sources)
  325.  FIVEWORDINLINE(0x2F3C, 6, 0x0105, 0x7000, 0xA82A);
  326. extern pascal ComponentResult SoundComponentStopSource(ComponentInstance ti, short count, SoundSource *sources)
  327.  FIVEWORDINLINE(0x2F3C, 6, 0x0106, 0x7000, 0xA82A);
  328. extern pascal ComponentResult SoundComponentPauseSource(ComponentInstance ti, short count, SoundSource *sources)
  329.  FIVEWORDINLINE(0x2F3C, 6, 0x0107, 0x7000, 0xA82A);
  330. extern pascal ComponentResult SoundComponentPlaySourceBuffer(ComponentInstance ti, SoundSource sourceID, SoundParamBlockPtr pb, long actions)
  331.  FIVEWORDINLINE(0x2F3C, 12, 0x0108, 0x7000, 0xA82A);
  332.  
  333.  
  334. /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
  335. /* interface for Audio Components*/
  336. /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
  337.  
  338.  
  339. /*Volume is described as a value between 0 and 1, with 0 indicating minimum
  340.   volume and 1 indicating maximum volume; if the device doesn't support
  341.   software control of volume, then a value of unimpErr is returned, indicating
  342.   that these functions are not supported by the device*/
  343.  
  344.  
  345. extern pascal ComponentResult AudioGetVolume(ComponentInstance ac, short whichChannel, ShortFixed *volume)
  346.  FIVEWORDINLINE(0x2F3C, 6, 0, 0x7000, 0xA82A);
  347. extern pascal ComponentResult AudioSetVolume(ComponentInstance ac, short whichChannel, ShortFixed volume)
  348.  FIVEWORDINLINE(0x2F3C, 4, 1, 0x7000, 0xA82A);
  349.  
  350.  
  351. /*If the device doesn't support software control of mute, then a value of unimpErr is*/
  352. /*returned, indicating that these functions are not supported by the device*/
  353. extern pascal ComponentResult AudioGetMute(ComponentInstance ac, short whichChannel, short *mute)
  354.  FIVEWORDINLINE(0x2F3C, 6, 2, 0x7000, 0xA82A);
  355. extern pascal ComponentResult AudioSetMute(ComponentInstance ac, short whichChannel, short mute)
  356.  FIVEWORDINLINE(0x2F3C, 4, 3, 0x7000, 0xA82A);
  357.  
  358.  
  359. /*AudioSetToDefaults causes the associated device to reset its volume and mute values*/
  360. /*(and perhaps other characteristics, e.g. attenuation) to "factory default" settings*/
  361. extern pascal ComponentResult AudioSetToDefaults(ComponentInstance ac)
  362.  FIVEWORDINLINE(0x2F3C, 0, 4, 0x7000, 0xA82A);
  363.  
  364.  
  365. /*This routine is required; it must be implemented by all audio components*/
  366. extern pascal ComponentResult AudioGetInfo(ComponentInstance ac, AudioInfoPtr info)
  367.  FIVEWORDINLINE(0x2F3C, 4, 5, 0x7000, 0xA82A);
  368. extern pascal ComponentResult AudioGetBass(ComponentInstance ac, short whichChannel, short *bass)
  369.  FIVEWORDINLINE(0x2F3C, 6, 6, 0x7000, 0xA82A);
  370. extern pascal ComponentResult AudioSetBass(ComponentInstance ac, short whichChannel, short bass)
  371.  FIVEWORDINLINE(0x2F3C, 4, 7, 0x7000, 0xA82A);
  372. extern pascal ComponentResult AudioGetTreble(ComponentInstance ac, short whichChannel, short *Treble)
  373.  FIVEWORDINLINE(0x2F3C, 6, 8, 0x7000, 0xA82A);
  374. extern pascal ComponentResult AudioSetTreble(ComponentInstance ac, short whichChannel, short Treble)
  375.  FIVEWORDINLINE(0x2F3C, 4, 9, 0x7000, 0xA82A);
  376. extern pascal ComponentResult AudioGetOutputDevice(ComponentInstance ac, Component *outputDevice)
  377.  FIVEWORDINLINE(0x2F3C, 4, 10, 0x7000, 0xA82A);
  378.  
  379.  
  380. /*This is routine is private to the AudioVision component.  It enables the watching of the mute key.*/
  381. extern pascal ComponentResult AudioMuteOnEvent(ComponentInstance ac, short muteOnEvent)
  382.  FIVEWORDINLINE(0x2F3C, 2, 129, 0x7000, 0xA82A);
  383.  
  384.  
  385. enum {
  386.     uppSoundParamProcInfo = kPascalStackBased
  387.          | RESULT_SIZE(SIZE_CODE(sizeof(Boolean)))
  388.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(SoundParamBlockPtr*)))
  389. };
  390.  
  391. #if GENERATINGCFM
  392. #define NewSoundParamProc(userRoutine)        \
  393.         (SoundParamUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppSoundParamProcInfo, GetCurrentArchitecture())
  394. #else
  395. #define NewSoundParamProc(userRoutine)        \
  396.         ((SoundParamUPP) (userRoutine))
  397. #endif
  398.  
  399. #if GENERATINGCFM
  400. #define CallSoundParamProc(userRoutine, pb)        \
  401.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppSoundParamProcInfo, (pb))
  402. #else
  403. #define CallSoundParamProc(userRoutine, pb)        \
  404.         (*(userRoutine))((pb))
  405. #endif
  406.  
  407.  
  408. #ifdef __CFM68K__
  409. #pragma lib_export off
  410. #endif
  411.  
  412. #if GENERATINGPOWERPC
  413. #pragma options align=reset
  414. #endif
  415.  
  416. #ifdef __cplusplus
  417. }
  418. #endif
  419.  
  420. #endif /* rez */
  421. #endif /* __SOUNDCOMPONENTS__ */
  422.